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ABSTRACT:  The  implementation  of  t>wo  different  image  hanoling 
systems  for  use  on  POP  11/45  minicomputers  is  documented. 
Micro-XAP  is  an  image  access  facility  for  UNIX  FORTRAN  users. 
Virtual  Arrays  are  a more  general  image  access  facility  for  UNIX 
LISP  users.  This  report  serves  as  a user's  guide  for  users  who 


will  interact  with  Micro-XAP  or  Virtual  Arrays. 
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1.  Introduction 

A numoer  of  image  processing  packages  run  on  the  Computer 
Vision  Laboratory's  POP  11/45.  Micro-XAP  and  Virtual  Arrays  are 
basic  image  processing  packages  that  run  under  the  UNIX  operating 
system.  Mini-XAP  is  a robust  image  processing  system  that  runs 
under  the  DOS  operating  system.  Since  the  Laboratory  only  runs 
UNIX,  the  Mini-XAP  system  is  not  currently  operated  and  will  not 
oe  documented  here. 

micro-XAP,  a collection  of  FORTRAN  callable  image  access 
routines,  wilt  be  presented  first.  Then  the  virtual  Array 
package  (VAP),  a collection  of  LISP  callable  image  access 
software,  will  be  described.  Some  general  software  support 
packages  for  LISP  users  will  be  oocumented  in  the  final  section. 
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2.  Micro-XAP 


Micro-XAP  is  a small  collection  of  image  access  and  creation 
routines  similar  to  the  kernal  routines  of  1108  XAP  C13.  The 
routines  were  originaly  coded  oy  Warty  Herman  and  have  since  been 
modified  by  Russ  Smith.  The  routines  are  FORTRAN  callaoUe  under 
the  UNIX  operating  system.  Output  pictures  are  created  by 
calling  the  routines: 

a)  SETUPW  once. 

b)  PWRITE  once  for  each  output  row* 

c)  XCLOSE  once. 


input  pictures  are  accessed  by  calling  the  routines: 

a)  SETUPR  once. 

b)  IPREAD  once  tor  each  input  row. 
c ) XCLOSE  once . 

There  are  two  utility  routines,  HEADER,  and  SCANOUT,  for 
acquiring  picture  header  information  and  displaying  pictures  on 
the  CRT  respectively. 

There  are  three  string  manipulation  routines.  PNAME.  NAMCAT,  ano 
LENGTH. 


The  last  routines  described  are.VPRINT,  vp,  phist,  and  1PER16, 


all  commands  to  the  UNIX  shell  written  by  Russ  Smith.  VPRINT  ano 


VP  display  pictures  on  the  system's  PRINTRONIX  line  printer. 
PHIST  lists  histograms  of  pictures  on  the  printer  while  iPERlo 
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takes  upto  2U  input  pictures  and  produces  a display  of  their 
composition  on  tne  CRT  display. 

2.U.I.  SETUP* 

CALL:  I = SETUP*  (ARE  A .NAME ,IW  ,SHI FT.3YPX  ) 

VALUE:  1 it  call  is  successful,  -1  if  an  error  occured 
EFFECT:  The  picture  NAME  is  associated  with  AREA  and  opened  for 
sequential  writing  (by  PwRITE).  Flags  are  set  to 
indicate  that  the  picture  NAME  is  open  for  writing  not 
for  reading.  SETUP*  builds  a XAP  header  for  the  output 
picture.  Tne  winoow  IW  and  the  bytes  per  pixel  are 

saved  in  the  header.  Tne  window  IW  is  checked  to  make 

sure  all  its  values  are  greater  than  or  equal  to  zero. 
Next,  it  is  determined  if  the  output  file  for  the 
picture  name  exists.  If  it  does  not,  it  is  created. 
The  winoow  IW,  the  file  description  for  the  picture  file 
N A m E » ana  the  SHIFT  are  saved  in  AREA.  Finally,  the 
header  is  written  out  to  the  picture  file. 

NOTES:  AREA  is  a 15  word  INTEGER‘S  work  area  for  xAP 

NAME  is  a 16  wore  INTEGFR**.  path  name  to  a UNIX  file 

that  will  be  created  or  which  already  exists.  NAME  is 
large  enough  to  hold  a 63  character  path  name. 

IW  is  a 4 word  INTEGER**,  defining  the  dimensions  of  the 
output  picture.  I W ( 3 ) is  the  number  of  columns  in  the 
picture.  Iw(4)  is  the  number  of  rows  in  the  picture. 
SHIFT  is  an  INTEGER**..  Each  picture  point  value 


written  to  picture  NAME  is  multiplied  by  2** SHIFT 
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2 .U. 2. 


BYPX  is  an  inteoer*4.  BYPX  is  the  number  of  bytes 
picture  point  in  the  output  picture.  BYPX  may  oe 
or  4 . 


per 

1,2, 


PWRITE 


C ALL  : 
VALUE  : 
EFFECT: 


NOTES  : 


I = PWRITE  (AREA, NUM, VECTOR) 

1 it  call  is  successful,  -1  it  an  error  occured 
PWRITE  writes  out  the  next  row  of  a picture.  If  NUM  is 
less  than  1,  t n en  PWRITE  returns.  The  column  dimension 
(lw(3>)  of  the  output  picture  is  taken  from  AREA. 
PwRITE  outputs  picture  point  values 

VECTOR(I),  ...  , VECT0RCIW13)) ♦NU'O  as  the  next  NUM  rows 
of  the  picture  associated  with  AREA  before  returning. 
Before  oeing  written  out,  each  point  in  VECTOR  is 
multiplied  by  2**SHIFT,  where  SHIFT  is  a parameter 
stored  in  AREA  by  SETUPw.  Each  group  of  IW(3)  words  in 


VECTOR  is  compressed  according  to  the  value  of  BYPX  that 
was  also  stored  in  AREA  by  SETUPW. 

SETUPW  must  be  called  before  PWRITE  is  called. 

AREA  is  a 15  word  INTEGER*4  work  area  for  XAP. 

NUM  is  an  INTEGER*4.  NUM  is  the  number  of  rows  in 


VECTOR  to  oe  written  out  to  the  picture  associated  with 
AREA. 


VECTOR  is  an  INTEGER*4  vector.  VECTOR  shoula  be  at 
least  Iw(3)*NUM  elements.  VECTOR  contains  the  picture 
point  values  to  be  written  out  to  the  picture  associated 


with  AREA 
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2.U.3.  XCLOSE 

CALL:  I = XCLOSE  (AREA) 

VALUE:  1 it  call  is  successful.  -1  if  an  error  occured 
EFFECT:  The  picture  file  associated  with  AREA  is  closed.  If  the 
user  tailed  to  complete  the  window  IW  associated  with 
AREA,  then  XCLOSE  prints  a warning  message.  It  the 
winoow  was  not  completed  and  AREA  is  associated  with  an 
output  tile,  then  execution  is  terminated.  XCLOSE 
returns. 

NOTES:  SETUPR  or  SETUPW  must  be  cal  lea  befor  XCLOSE. 

AREA  is  a 15  word  INTE6ER*4  work  area  for  XAP. 


2.0.4.  SETUPR 

CALL:  I = SETUPR  ( ARE  A ,N AME  , I W ,SHI F T , DEPTH  ,PTR  ) 

VALUE:  1 it  call  is  successful,  -1  it  an  error  occured 
EFFECT:  The  picture  NAME  is  associatea  with  AREA  and  opened  for 
sequential  reading  (by  IPREAD).  Flags  are  set  to 
indicate  that  the  picture  NAME  is  open  for  reading  but 
not  tor  writing.  The  XAP  header  is  read  in  and  the 
following  parameters  are  saved  in  AREA:  The  number  of 
columns,  number  of  rows,  bytes  per  pixel,  the  file 
descriptor  tor  the  picture  NAME,  the  window,  ana  SHIFT. 
The  user  input  window  IW  is  checked  against  the  winoow 
from  the  header.  If  the  window  IW  is  invalid  or  DEPTH 
is  less  than  1,  then  an  error  message  is  printed  and 
execution  is  terminated.  The  window  and  bytes  per  pixel 
obtained  from  the  header  are  used  to  initialize  control 
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parameters  stored  in  AREA.  These  parameters  allow 
IPREAD  to  extract  the  appropriate  columns  (as  specified 
by  1 W ( 1 ) and  I W < 3 ) > from  an  input  row  for  storage  in  the 
array  passed  to  IPREAD.  The  vector  PTR  is  initialized 
by  setting  PTR(I)  to  1 1 where  I = 1i...*DEPTH. 


NOTES:  AREA  is  a 15 

word  INTEGER*4 

work  area  for 

X AP 

• 

NAME  is  a 16 

word  INTEGER*4 

path  name  to 

an 

existing 

X A P picture. 

This  path  name 

can  be  uP  to 

63 

characters 

long. 

I W i s a 4 

word  INTEGFR*4 

vector  contain 

a window 

specification 

for  NAME. 

SHIFT  is 

an  INTEGER**.. 

Each  picture 

value  is 

multiplied  oy 

2**SHIFT  oefore 

it  is  placeo 

i n 

ARRAY. 

DEPTH  is  an  INTEGER***.  DEPTH  is  the  maximum  numoer  of 
rows  of  picture  NAME  user  will  keep  in  array  array. 


PTR  is  a DEPTH  word  INTEGER*^  vector  of  suDScript 
values.  P T R ( 1 ) is  the  subscript  of  the  least  recently 
read  row.  PTR  (DEPTH)  is  the  subscript  of  the  most 
recently  read  row. 

2.0.5.  IPREAD 

CALL:  I = IPREAD  (AREA, NUM, DEPTH, PTR, ARRAY, RLENGTH) 

VALUE:  1 when  row(s)  properly  read  in,  0 when  no  more  rows  in 
window,  -1  when  an  error. 

EFFECT:  It  NUM  is  less  than  1,  then  PREAD  returns  a zero 
immediately.  If  all  of  the  picture  rows  in  the  window 
IW  associated  with  AREA  have  been  passed  to  the  user. 


mmitm — m 


NOTES  : 
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then  IPREAD  returns  the  value  1,  otherwise  it  returns  0. 
If  at  least  one  row  of  the  window  of  the  input  picture 
associates  with  AREA  remains  to  be  read,  then  the  row  is 
input.  The  control  parameters  stored  in  AREA  (and 
calculated  by  SETUPR)  are  used  to  unpack  the  points  in 
the  input  row  belonging  to  the  window  Iw»  The  points  in 
the  window  are  multiplied  by  2**SHJFT  as  they  are  copied 
to  ARRAY  ( 1 ,PTR  ( 1 ) ) , . . . , ARR A Y( 1W( 3) ,PTR  ( 1 ) ) . The  P T R 
vector  associated  with  AREA  is  then  rotated.  That  is, 
D T R ( I ) is  set  to  PTR(I*1),  for  I = I,..., DEPTH-1. 

PTR(DEpTH)  is  set  to  the  original  value  of  PTR(1).  The 
dimension  of  the  array  ARRAY  associated  with  AREA  is 
RLENGTH  x DEPTH.  The  apove  procedure  is  performed  NUM 
time  before  IPREAD  returns  unless  the  window  is 
completeo  oefore  NUM  rows  are  processed.  It  should  be 
noted  that  at  most  DEPTH  rows  of  the  input  picture  are 
in  ARRAY  at  any  one  time.  The  oldest  row  (nearest  the 
too  of  the  window)  oegins  at  ARRAY  (1,PTR(1))  and  the 
newest  row  (lowest  row  read  in  the  window  so  far)  begins 
at  ARRAY  ( 1 ,PTR ( DEPTH)  ) . 

SETUPR  must  be  called  oefore  IPREAD  is  called. 

AREA  is  a 15  word  INTEGERS  work  area  for  XAP. 


NUM 

is  an  INTEGER***  containing 

the  number 

of 

rows 

of 

the 

picture  associated  with 

AREA  to  be 

read 

into 

the 

array  ARRAY. 

DEPTH  is  an  INTE6ER*4  containing  the  maximum  number  of 
rows  of  picture  NAME  the  user  will  keep  in  array  ARRAY, 
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PTR  is  a DEPTH  word  INTEGER***  vector  of  suoscript 
values.  P T R ( 1 ) is  the  sue  script  of  the  least  recently 
reaa  row.  PTR(DEPTh)  is  the  subscript  of  the  most 
recently  read  row. 

ARRAY  is  an  RLENGTh  x DEPTH  word  INTESER*4  array  to 
hola  rows  of  picture  NAME. 

RLENGTh  is  an  INTEGER***  that  is  the  row  length  of  ARRAY 
and  the  maximum  window  width  SETUPR  ana  IPREAD  will 
allow. 

.0.6.  HEADER 

CALL:  I = HEADER  (INAME.  HBUF ) 

VALUE:  1,  if  there  is  no  I/O  error  while  reading  the  header 
record  of  file  I N A M E » otherwise  header  terminates. 

EFFECT:  The  header  information  on  (picture)  INAME  is  stored  in 
the  vector  HBUF.  If  file  INAME  does  not  exist  or  an  I/O 
error  occurs  while  HEADER  reads  the  header  record,  then 
an  error  message  is  printed  and  execution  is  terminated. 

NOTES:  INAME  is  a 16  word  INTEGER*^  vector  containing  a path 

name  to  a UNIX  tile. 

HBUF  is  a 3 word  INTEGER***  vector. 

HBUF(I)  is  the  column  length  of  the  picture. 

HBUF ( 2 ) is  the  row  length  of  the  picture. 

HBUF ( 3 ) is  the  number  of  bytes  per  pixel  for 
the  picture  (only  1.2.  or  4). 
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2.C.7. 

CALL 
VALUE 
EFFECT: 


NOTES 

2 . U . ; . 

CALL 

VALUE 

EFFECT 

NOTES 


2 • U • J . 

C ALL 
VALUE 
EFFECT 


SCANOUT 

SCANOUT 

None 

SCANOUT  prompts  the  user  for  a picture  file  name  and  a 
winaow  specification.  SCANOUT  copies  the  window  of  the 
picture  to  the  photographic  and  video  display.  The 
scanner  must  De  properly  initialized. 

The  picture  values  should  be  in  the  range  0 to  63. 


P N A M E 


CALL  PN APE  (TPLATE  .NAME. NUM) 

None 

The  characters  in  TPLATE  are  concatenated  with  the  ASCII 
character  r e p r e s en t a t i on  of  the  number  NUM  and  stored  in 
NAPE.  NAME  can  be  used  as  a XAP  picture  name. 

TPLATE  is  a UNIX  path  name.  TPLATE  is  assumed  to  be 
dimensioned  large  enough  to  contain  48  characters. 

NAME  is  assumed  to  be  dimensioned  large  enough  to 
contain  64  characters. 

NUM  is  a single  word  integer. 

The  completed  XAP  picture  name  must  be  less  than  64 
characters  long. 

NAMC AT 

CALL  NAM CAT  (NAME1,LENGTH1,NAME2,LENGTH2,CATNAME) 

: None 

: The  character  string  in  NAME1  of  length  LENGTH1  is 
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concatenatea  with  the  string  NAME2  of  length  LENGTH?  ana 
stored  in  the  vector  CATNAME.  A blank  character  is 
added  to  the  string  in  CATNAME  so  that  the  string  in 
CATNAME  can  oe  used  as  a UNIX  file  name. 

NOTES:  NAmEI  is  an  integer  vector  containing  a character 
string.  NAMEI  is  assumed  to  oe  dimensioned  large  enough 
to  hold  a string  of  length  LENGTHl  . 

NAME2  is  an  integer  vector  containing  a character 
string.  NAME2  is  assumed  to  oe  dimensioned  large  enough 
to  hold  a string  of  length  LENGTH?. 

CATNAME  is  an  integer  vector  to  contain  the 
concatenation  of  NAmEI  and  NAME?.  CATNAME  is  assumed  to 
be  dimensioned  large  enough  to  hold  a string  of  length 
LENGTHl  ♦ L t NG  T H 2 ♦ 1. 

EXAMPLE:  The  following  code  saves  the  concatenation  of  the  two 
String  " /dir”  and  "/pet"  in  INAME. 

INTEGER  Nl  ( 16)  ,N2 ( 1 6) , I NAME ( 16  ) 

DATA  N1 (1 >/"/oir"/ 

DATA  N 2 < 1 ) / " / D C t " / 

CALL  NAMCAT  (Nl ,4 ,n2 ,4,  INAME ) which  is  equivalence  to 

doing 

CALL  NAMCAT  ("/dir"  4 "/pet"  4 INAME) 

2.0.10.  LENGTH 

CALL:  V = LENGTH  (INAME, NLENGTH) 


VALUE:  The  length  of  the  string  in  INAME. 

EFFECT:  LENGTH  returns  the  (byte)  length  of  the  character  string 
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storea  in  the  integer  vector  INAME.  NLENGTH  is  assumed 
to  oe  the  dimension  (INTEGER*4)  of  INAME. 

NOTES:  INAME  ana  NLENGTH  are  Doth  INTEGER*4  input  arguments. 

The/  are  not  modified. 

2 . d. 1 1 . VPR INT 

CALL:  % vprint  [N  or  -ND  p i c t u re -n a me  1 ...  pict ure-name<n> 

EFFECT:  VPRINT  lists  out  the  picture  tiles  p i c t u r e - name  1 ... 

p i c t u re -na me <n>  . The  pixels  of  each  picture  are  shifted 
N places  to  the  left  (or  right  when  a dash  precedes 

the  number  n)  oefore  the  tour  least  significant  bits  of 
each  shitted  pixel  are  used  to  select  one  of  sixteen 
possiDle  grey  levels  for  display  on  the  PRINTRONIX  line 
printer.  All  pictures  are  assumed  to  be  one  byte  per 
pixel.  Each  picture  file  must  be  in  PDP/XAP  format. 
Pictures  that  are  wider  than  64  pixels  will  be  printed 
in  64  column  strips.  The  complete  image  can  be  viewed 
by  assembling  the  picture  strips  together. 

NOTES:  It  no  shift  is  given,  then  the  first  picture  name  cannot 
begin  with  a dash  or  a digit. 

2.0.12.  VP 

CALL:  * vp  IN  or  -N]  picture-namel  ...  picture-name<n> 

EFFECT:  VP  lists  out  the  picture  files  picture-namel  ... 

p i c t u r e -na me<n> . The  pixels  of  each  picture  are  shi  teo 
N places  to  the  left  (or  right  when  a dash  precedes 

the  numoer  n)  before  the  four  least  significant  bits  of 


w 
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NOTES  : 

2.0.13. 

C ALL  : 
EFFECT  : 


NOTES  : 

2 .0. 14  . 

C ALL  : 
EFFECT: 


each  shifted  pixel  are  used  to  select  one  of  sixteen 
Dossiple  grey  levels  tor  display  on  the  PRINTRCNIX  line 
printer.  All  pictures  are  assumed  to  oe  one  byte  per 
pixel.  Each  picture  tile  must  be  in  PDP/XAF  format. 
Pictures  that  are  wider  than  128  pixels  will  oe  printed 
in  12S  column  strips.  The  complete  image  can  be  viewed 
by  assembling  the  picture  strips  together. 

If  no  shift  is  given,  then  the  first  picture  name  cannot 
begin  with  a dash  or  a digit. 

PHIST 

7.  phist  L-]  pi  c t ure-name  1 ...  p i c t u r e -n  a me  <n  > 

A histogram  for  each  PDp/xAP  formatted  picture 
p i c t u r e -name  1 ...  p i c tu re -na me<n>  is  printed.  If  the 

dash  is  present,  then  a listino  of  the  histograms  is 

sent  to  the  standard  output.  If  the  oash  is 

missing,  then  a listing  of  the  histograms  including  par 
graphs  will  be  plotted  on  the  PRINTRONIX  line  printer. 

If  the  optional  dash  is  missing,  then  the  first 

picture  name  cannot  begin  with  a oash. 

1 PE  R 1 6 

X 1 pe  r 1 6 

1per16  is  an  interactive  routine  to  create  one  CRT 
display  image  from  up  to  twenty  different  PDP/XAP 
formatted  input  pictures.  1per16  will  place  the 
pictures  in  the  display  image  or  the  user  can  manually 


r ' ^ 
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specify  the  composition  of  the  display.  Any  row  of  the 
display  can  have  pieces  of  at  most  eleven  different 
input  pictures. 

NOTES:  The  CRT  display  should  t>e  turned  on,  set  online  to  the 
p0Pl1/4b,  and  set  up  to  accept  the  desired  picture  size. 
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3.  Virtual  Arrays 

Tne  Virtual  Array  package  (VAP)  is  a collection  oi  image 
access  and  creation  routines.  The  routines  are  LISP  functions 
running  under  the  UNIX  operating  system.  The  elements  of  a 
virtual  array  (pixels)  can  be  N oytes  long,  where  N is  a power  of 
two.  When  elements  are  accessed  (row  or  points),  the  Virtual 
Array  package  returns  values  as  either  ARRAYs  or  VECTyRs.  So 
elements  can  oe  accessed  as  integer,  real,  douole  precision,  or 
complex  values,  or  as  vectors  of  binary,  integer,  real,  double 
precision,  or  complex  values.  Unfortunately,  LISP  SYS  calls  only 
work  with  ARRAVs;  thus  writing  values  out  to  a virtual  array  is 
more  complicated  than  it  need  be. 

The  following  functions  are  defined  by  the  Virtual  Array 
package . 

3.0.1.  VAC:  Virtual  Array  Creation 

call:  (VAC  ' V A 1 0 FILE-NAME  X-SIZE  Y-SIZE  BYTE-SIZE 
[POINT-ROW?  C M I N - X MAX-X  MIN-Y  MAX-Y]]) 

VALUE:  Tne  pointer  array  that  is  constantly  bound  to  VAio 
EFFECT:  VAC  creates  the  file  FILE-NAME  and  allocates  enough 
space  in  FILE-NAME  to  maintain  an  X-SIZE  by  Y-SIZE 
virtual  array.  When  BYTE-SIZE  is  positive,  each  element 
of  the  virtual  array  is  2*  MBYTE-SIZE)  oytes  long.  When 
BYTE-SIZE  is  negative,  the  elements  "are  (length  1) 
ARRAYS  or  VECTORS,  which  associate  a data  type  with  the 
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NOTES: 


data  in  the  virtual  array.  The  initial  value  of  each 
element  is  zero.  After  creating  the  tile*  VAC  closes 
the  file  (VAX)  then  re-opens  it  using  VAO.  See  V AO's 
description. 

FILE-NAME  is  a string  nooe  defining  a valid  UNIX  file. 

X-SIZE  is  the  maximum  allowable  index  for  the  x 

dimension  (legal  subscripts  run  from  0 through  X-SIZE). 

Y-SIZE  is  the  maximum  allowable  index  for  the  y 

dimension  (legal  subscripts  run  from  0 through  Y-SIZE). 


6 YTE-SIZE 

allows  the  user  to 

define 

the 

form  of 

the 

elements 

of  the  virtual 

array. 

I f 

BYTE-SIZE 

i s 

positive,  then  each  element  is  2 ** ( B Y T E - S I Z E ) bytes  long 
and  vAP  routines  return  data  (VAID  6)  in  a byte  ARRAY, 
If  bYTE-SlZfc  is  greater  than  -11,  then  each  element  is  a 
(length  1)  VECTOR  with  type  IBYTE-S1ZEI  and  VAP  routines 
return  data  in  an  appropriate  VECTOR.  If  BYTE-SIZE  is 
less  than  -10,  then  each  element  is  a (length  1)  ARRAY 
with  type  IBYTe-SIZE  - 2 C I and  VAP  routines  return  data 
in  an  appropriate  ARRAY. 

The  purpose  of  allowing  negative  valued  BYTE-SIZE 
arguments  is  that  it  associates  a type  with  the  data  in 
a virtual  array  and  automatically  initializes  VAID  at 
open  time,  so  that  users  can  reference  the  data 
properly.  for  example,  a virtual  array's  elements  would 
be  word  integer  (array),  doub l e -pre c i s i on  integer 
(vector),  or  complex  (vector),  if  BYTE-SIZE  had  value 


-25,  -6,  or  -9,  respectively 
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POINT-ROW?  is  an  optional  argument.  If  t nis  argument 
is  missing  or  NIL.  then  the  virtual  array  is  openeo  for 
point  accessing  (i.e.  all  read  and  write  requests  access 
a single  element  of  the  virtual  array).  If  POINT-ROW? 
is  non-NIL.  then  the  virtual  array  is  openeo  for  row 
accessing  and  all  read  and  write  functions  (except  V A 
and  V A W ) transfer  a row  of  element  from  the  window  of 
the  virtual  array. 

MIN-X,  * A X - X . MIN-Y,  MAX-Y  define  a window  of  the 
virtual  array.  "read(write)-ne»t"  and  "reao(write)-row" 
functions  won't  reference  points  outside  of  the  window. 
"read(write)-point"  functions  will  reference  any  point 
fo  the  virtual  array  regardless  of  the  winoow.  The 
default  values  tor  missing  window  specification 
arguments  are  0,  X-SIZE.  G,  Y-SIZE,  respectively. 

3.U.2.  VAO:  Virtual  Array  Opening 

CALL:  (VAO  'VA1D  FILE-NAME  [POINT-ROW? 

[MIN-X  MAX-X  MIN-Y  MAX-Y33) 

VALUE:  The  pointer  array  that  is  constantly  Douno  to  VA1D 
EFFECT;  VAO  closes  any  virtual  array  currently  associated  witn 
VAID.  Then  VAO  opens  the  virtual  array  stored  in  the 
tile  with  name  FILE-NAME  ana  associates  it  with  VAID. 
If  the  file  does  not  exist,  then  VAO  prints  an  error 
message  and  then  evaluates  an  (error  20).  VAO  reads  in 
a 6-oyte  heaoer  record  that  contains  the  values  X-SIZE, 
Y-SIZE,  and  BYTE-SIZE;  these  were  set  at  creation  time. 
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The  window 

i s 

defaulted  to 

the 

entire  virtual 

a r r ay  . 

I f 

POI NT-ROW? 

i s 

absent,  then 

VAO 

conditions 

VA  ID 

for  point 

accessing 

and  returns. 

Otherwise* 

the 

value 

o f 

POINT-ROW? 

1 

s checked.  If 

i t 

is  NIL, 

then 

V A I D 

i s 

c ono i t i one  d 

for  point 

accessing* 

else 

V A I D 

i s 

conditioned  tor  row  accessing.  Now*  V AO  modifies  the 
winaow  by  as  many  arguments  (MIN-X  ...  MAX-Y)  as  the 
user  supplies.  If  this  new  window  extends  oeyond  the 
boundary  of  the  virtual  array*  then  VAO  evaluates  an 
(ERROR  2 U ) . Otherwise,  VAO  returns  to  the  user. 

NOTES:  FIlE-nAmE  is  a string  nooe  defining  a valid  UNIX  file. 

X-SIZE  is  the  maximum  allowaole  index  for  the  x 

dimension  (legal  subscripts  run  from  0 through  X — SIZE) • 
Y-SIZE  is  the  maximum  allowable  index  for  the  y 

dimension  (legal  subscripts  run  from  0 through  Y-SIZE)* 
for  discussion  of  8YTE-SIZE  see  NOTES  of  VAC. 

MIN-x,  m a X - X , MIN-Y,  MAX-Y  define  a window  of  the 
virtual  array.  "read(write)-next"  and  "read(write)-rox" 
functions  won't  reference  points  outside  df  the  window. 
" reao(write) -point"  functions  will  reference  any  point 
to  the  virtual  array  regardless  of  the  window. 

3.0.5.  VA;  Virtual  Array  Reading  (Point) 

CALL:  (VA  V A I D X Y) 

VAlUE:  The  array  (or  vector)  containing  the  value  of  the  point 
at  coordinates  (X,Y)  of  the  virtual  array  associated 


with  V A I 0 
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EFFECT:  The  element  (X,Y)  of  the  virtual  array  associated  with 
VAID  is  loaded  into  the  array  (VAID  5).  VA  returns  the 
ARRAY  or  VECTOR  in  (VAID  6)  to  the  user.  The  two  arrays 
(VAID  5)  and  (VAID  6)  are  assumed  to  reference  the  same 
storage  area. 

NOTES:  X is  an  inaex  tor  the  x dimension.  X is  not  checked 

tor  being  in  range. 

Y is  an  index  for  the  y dimension.  Y is  not  checked 
for  being  in  ranoe  • 

EXAMPLE:  The  following  code  will  make  a histogram  of  picture 
"/pict"  sampled  every  other  column  and  every  other  row. 
The  picture  is  assumed  to  be  one  byte  per  picture  point. 
( V A 0 'ID  "/pict") 

(setq  HIST  (vector  255  6)) 

(mapn  0 (ID  2)  (lambda  (-y) 

<cond  [<terop  (logand  1 -y)>3 

[T  <mapn  0 (ID  1)  (lambda  (-x) 

<cona  [<  zerop  (logand  1 -y>>] 

CT 

< se  t q I ( < V A I D -x  -y  > 1 ) > 

< H I S T I (adol  < H I S T l>)>]> 

) > 3 > 

) ) 

(VAX  'ID) 


3.0.4.  VAw:  Virtual  Array  writing  (Point) 


CALL:  (VAw  VAID  X Y VALUE) 
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VALUE:  The  array  VALUE 

EFFECT:  VAw  replaces  element  (X.Y)  of  the  virtual  array 
associateo  with  VAID  Py  VALUE*  VALUE  is  assumed  to  be 
an  ARRAY  large  enought  to  hold  at  least  one  element  of 
the  virtual  array*  VAW  returns  VALUE. 

NOTES:  X is  an  index  for  the  x dimension.  X is  not  checked 

tor  being  in  range  • 

Y is  an  index  for  the  y dimension.  Y is  not  checked 
for  being  in  range  . 

Example:  The  following  code  will  place  a 5x5  square  with  value  64 
in  the  picture  "/pict".  The  square  will  be  centered  at 
point  (10.15)  of  ,,/pict,,.  "/pict"  is  assumed  to  be  a 
oyte  picture. 

( V A 0 'ID  "/pict") 

(setq  POINT  (Array  1 4)) 

(POINT  1 64) 

(mapn  13  17  (lambda  ( -y ) 

<mapn  8 12  (lambda  (-x) 

< V A W ID  -x  -y  POI NT> 

)> 

)> 

(VAX  'ID) 

3.U.5.  VAR:  Virtual  Array  Reading  (Row) 

CALL:  (VAR  VAID  Y) 

VALUE:  The  array  (or  vector)  containing  the  Yth  row  of  the 
virtual  array  associateo  with  VAID. 


Image  Processing  Software  under  UNIX 


PAGE  3-7 


EFFECT:  VAR  reaos  row  V of  the  window  oefined  on  the  virtual 
array  associated  with  VAID  into  the  array  in  (VAID  5). 


If 

VAID 

wa  s opened  for 

point  accessing. 

then  VAR 

reads 

i n 

the 

point  at  ( M i N-x 

,¥).  If  row  Y is 

outside  the 

user 

3ef i ned 

window,  then 

VAR  evaluates  an 

(ERROR  20). 

VAR 

returns  (VAID  6). 

NOTES:  (VAID  5)  is  a byte  array  for  a point  (or  row  of  points). 

(VAID  6)  is  an  array  (or  vector)  of  user  chosen  type 

that  is  equivalenced  to  (vaid  5). 

EXAMPLE:  The  following  code  opens  the  virtual  array 

"/ o i c t u re s / s 1 " , reads  in  and  lists  its  first  row,  and 

then  closes  the  virtual  array. 

(V  AO  ID  " /pictures/si”  t) 

(VAR  ID  1 ) 

( c o no [ < a r r a y p (vaio  o ) > <csetq  TOP  (arrayl  (vaid  6))> 

<csetq  BOT  1 >] 

Ct  <csetq  TOP  (VECTORl  (vaio  6))> 

< c se  t q EPT  0>J) 

( c s e t q R nil) 

(oidpn  TOP  oOT  (lamoda  ( -i ) 

<setq  R (cons  <(vaid  6)  -i>  R)>)) 

(print  R ) 

(VAX  '10) 

3*0.6.  V AWR : Virtual  Array  Writing  (Row) 

CALL:  (VAkR  VAID  r VALUE) 


VALUE: 


The  array  VALUE 
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EFFECT:  VAWR  replaces  row  Y of  the  window  defined  for  the 
virtual  array  associateo  with  VAID  by  the  elements  in 
VALUE.  If  VAID  was  opened  for  point  accessing.  then 
VAWk  replaces  the  point  at  (MIN-X,Y).  If  row  Y is 
outside  of  the  user  defined  window,  the  VAWR  evaluates 
an  (ERROR  2 U).  VAWR  returns  VALUE. 

NOTES:  VALUE  is  an  ARRAY  (it  cannot  be  a VECTOR)  containing  a 

row  of  elements.  The  data  in  VALUE  are  written  out  to 
the  virtual  array. 

EXAMPLE:  The  following  code  will  produce  a 15*15  picture  with  a 
5*5  square  (with  value  64)  centered  in  it.  Each  element 
of  the  virtual  array  is  a byte  long.  The  background  has 
value  zero. 

(VAC  'ID  "/square", 14  14  0 T 5 V 5 9) 

(csetq  ROW  (Array  5 4)) 

(mapn  1 5 (lambda  (-X) 

<POW  -*  64  >)) 

(mapn  5 9 (lambda  (-y) 

< V A W R ID  -y  R Ow > ) ) 

(VAX  'ID) 

3.J.7.  VAN:  Virtual  Array  Reading  (Next  Row  or  Point) 

CALL:  (VAN  VAID) 

VALUE:  The  array  (or  vector)  containing  the  next  point  (VAID 
opened  for  point  accessing)  or  the  next  row  of  points 
(VAID  opened  for  row  accessing)  of  the  virtual  array 
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a ssociateo  with  VAID. 

EFFcCT:  VAN  reads  the  next  point  (VAID  opened  for  point 

accessing)  or  the  next  row  (VAID  opened  for  row 
accessing)  into  the  ARRAY  in  (VAID  5).  If  the  point  or 
row  is  outside  of  the  window  defined  on  the  virtual 
array*  then  VAN  evaluates  an  (ERROR  20).  VAN  returns 
( vAi D 6),  an  array  (or  vector)  containing  the  next  point 
or  row. 

EXAMPLE:  The  following  code  computes  the  average  value  of  a 
picture  < M / p i c t ” ) whose  elements  are  one  Oyte  long. 

(VAO  'ID  "/pict") 

(csetq  SUW  (csetq  NPT  (Douole  0))) 

(attempt  [prog  <> 

TOP  <csetq  SUM  (plus  SUM  <(VAN  ID)  1 >)> 

< c se  t q NPT  ( ad  o 1 NPT)> 

<oo  T OP  > ] 

[203) 

(VAX  'ID) 

(print  (cons  "AVERAGE  VALUE  IS"  (quotient  SUM  NPT))) 
3.U.O.  V A w N : Virtual  Array  writing  (Next  Row  or  Point) 

CALL:  (VAWN  VAID  VALUE) 

EFFECT:  VAID  replaces  the  next  point  (VAID  opened  for  point 
accessing)  or  the  next  row  (VAID  opened  for  row 
processing)  of  the  user  window  of  the  virtual  array 
associated  with  VAID  with  the  element  (s)  stored  in  the 
array  VALUF.  If  the  point  or  row  is  outsidee  of  the 
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user  defined  winoowf  then  VAWN  evaluates  an  (ERROR  20). 
VAWN  returns  VALUE. 

NOTES:  VALUE  is  an  ARRAY  (it  can  not  be  a VECTOR)  containing  a 
single  element  (if  VAID  opened  for  point  accessed)  or  a 
row  of  elements  (if  VAID  was  opened  for  row  accesses). 
The  data  in  VALUE  are  written  out  to  the  virtual  array. 
EXAMPLE:  The  following  code  will  place  a 5x5  square  with  vtalue  64 
in  the  picture  "/pict".  The  square  will  be  centered  at 
point  (10.  15).  "/pict"  is  assumed  to  be  a byte 

picture. 

( V A 0 'ID  "/pict”  nil  8 12  13  17) 

(csetq  POINT  (Array  1 4)) 

(POINT  1 64) 

(attempt  [prog  < > 

TOP  < V A W N ID  P 0 1 N T > 

<90  T0P>] 

C 2 03  ) 

(VAX  'ID) 

3.O.V.  N V A : Virtual  Array  Reading  (Next  Point) 

CALL:  ( N V A VAID) 

EFFECT:  N V A reads  in  the  next  element  of  the  virtual  array 
associated  with  VAID.  NVA  ooes  no  window  checking  and 
does  not  keep  track  of  the  coordinates  of  the  currently 
accessed  point  of  the  virtual  array. 


3.0.10. 

CALL: 

EFFECT: 


3.0.11. 

C ALL  : 
VALUE  : 

EFFECT; 

NOTES  : 

EXAMPLE  : 
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N V A w : Virtual  Array  Writing  (Next  Point) 

( N V A W VAIL  loptional  arguments]) 

N V A w writes  out  The  data  stored  in  (VAID  5)  as  the  value 
of  the  next  element  of  the  virtual  array  associated  with 
VAID.  N V A W does  no  window  checking  and  does  not  keep 
track  of  the  coordinates  of  the  currently  accessed  point 
of  the  virtual  array. 

SVA:  Updating  a Point  or  Row  Value 

(SVA  VAID  [optional  arguments]) 

Tne  array  (or  vector)  containing  the  updated  row  or 
point  of  the  virtual  array  associated  with  VAID 
SVA  replaces  the  last  referenced  elements  (VAID  openeo 
for  point  accessing)  or  row  (VAID  openeo  for  row 
accessing)  of  the  virtual  array  associated  with  VAID 
with  the  current  contents  of  the  array  (VAID  5).  SVP 
returns  (VAID  6). 

(VAID  5)  is  a byte  array  eauivalenced  with  the  array  or 
vector  in  (VAID  6). 

The  following  code  will  add  one  to  each  point  in  the 
byte  picture  "/pictures/pl". 

( V A 0 'ID  "/pictures/pl") 

(ATTEMPT  [prog  < > 

TOP  < S V A ID  (<ID  5 > 1 <add  1 (<VAN  ID  > 1)>)> 
<go  T OP > ] 

[20]) 


(VAX  'ID) 


1 
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3.0.12.  VAX:  Virtual  Array  Closing 

CALL:  (VAX  'VAID) 

VALUE:  The  pointer  array  that  has  oeen  constantly  oound  to 
VAID. 

EFFECT:  VAX  closes  the  tile  associated  with  the  virtual  array 
controlled  by  VAID,  if  there  is  one.  VAX  returns  the 
value  of  V A 1 D (a  pointer  array).  VAX  evaluates  an 
(ERROR  20)  if  its  input  argument  is  not  an  atomic 
symDOl.  VAX  initializes  VAID,  if  neccessary,  by  making 
its  value  a 16  place  pointer  array  of  NILS. 

NOTES:  After  the  virtual  array  associated  with  VAID  is  closed* 

no  input  or  output  (ex.  VA  or  VAW)  should  be  performed 
with  VAID  until  some  virtual  array  is  opened  (V AO)  and 
associated  with  VAID.  Failure  to  ooey  this  restriction 
will  result  in  unusual  behavior  on  the  standard  input 
tile  (file  Descriptor  0),  especially  when  a program  is 
run  in  oackground. 


3.U.13.  VAID:  Virtual  Array  IDentifier 


VAID  stanos  for  Virtual  Array  IDentifier.  VAID's  value  is  a 
16  place  pointer  array  whose  values  are  as  follows:  (VAC  VAO  VAX 
initialize  this  variable,  not  user) 

1 is  maximum  x dimension  value  (X-SIZE.  or  A columns  - 1). 

2 is  maximum  y dimension  value  (V-SIZE.  or  A rows  - 1). 

3 is  log  base  2 of  the  oyte  length  of  a virtual  array  element 

(computed  from  BYTE-SIZE). 

A is  the  UNIX  file  descriptor  for  the  virtual  array. 


MU 


Image  Processing  Software  under  UNIX 


PAGE  3-13 


■ 


5 is  a byte  ARRAY  pig  enough  to  hoi  a a single  element  or  a row 

of  elements*  deoenoing  on  whether  VAID  was  opened  for 
point  access  or  row  access* 

0 is  initialized  to  be  identical  to  (VAID  5).  If  the  user 
wants  to  receive  an  ARRAY  or  VECTOR  structure  other  than 
a byte  array*  then  he  shoulo  modify  (VAID  6).  For 
example,  <VAID  6 IRPLACA  (ARRAY  1 5)  (*CAR  (VAID  5)))> 
would  allow  the  user  to  directly  reference  elements  of  a 
virtual  array  if  BYTE-SIZE  was  1. 

7 is  the  x cooroinate  of  the  beginning  of  the  last  ooint(s) 
accessed. 

6 is  the  y coordinate  of  the  last  row  accessed. 

9  is  the  oyte  length  of  records  to  be  read  or  written.  For 
point  accessing  this  is  the  length  of  a single  element. 
For  row  accessing  this  is  [MAX-X  - *IN-X  ♦ 13  times  the 
length  of  a single  element. 

10  is  the  oyte  length  of  a row  of  elements  (of  the  virtual 

array,  not  the  window). 

11  is  a position  vector  used  for  "seeking"  arouno  the  virtual 

array  file. 

12  is  the  POINT-ROW?  flag.  If  point  accessing  was  requested, 

then  (VAID  12)  is  NIL,  otherwise,  it  is  non-NIL. 

13  is  the  minimum  x coordinate  a "reao-next",  "xrite-next", 

"read-row”,  or  "write-row"  function  can  access-  in  the 

virtual  array. 

14  is  the  maximum  x coordinate  a "read (wr i te ) -ne x t " or  a 

" read(write)-row"  function  can  access  in  the  virtual 

array. 

15  is  the  minimum  y coordinate  a ”read(write)-ne»t(row)" 

function  can  access  in  the  virtual  array. 

16  is  the  maximum  y coordinate  a ”reao(write)-next(row)" 

function  can  access  in  the  virtual  array. 


3.0.14,  VPSK:  Virtual  Array  Seek  Utility 


CALL:  (VPSK  VAID  X Y) 

VALUE:  Non-NIL 

EFFECT:  VPSK  conditions  the  virtual  array  file  of  VAID  so  that 


L 


A 
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the  next  read  or  write  wilt  effect  the  element  at 
coordinates  <X,Y).  VPSK  calculates  the  displacement  of 
element  (X,Y).  If  the  file  is  already  at  that  position, 
then  VPSK  returns.  If  the  file  is  positioned  near  the 
element,  then  VPSK  does  a relative  seek  to  the  new 
position.  Otherwise  VPSK  does  an  absolute  seek  to  the 
new  position.  This  last  seek  is  actually  two  seeks, 
because  the  byte  displacement  can  oe  greater  than  a POP 
11  word.  VPSK  remembers  the  position  of  the  file  as 
being  the  beginning  of  the  addressed  element. 

NOTES:  Users  should  never  have  to  call  this  routine. 

3.U.15.  VADUMP:  List  Status  of  VAID 

t 

CALL:  (VADUMP  'VAID) 

VALUE:  NIL 

EFFECT:  The  contents  of  the  virtual  array  identifiers  VAID  are 
listeo  out.  See  VAID  for  a complete  description  of  the 
form  of  VAID. 

3.U.16.  PRTOUT 


CALL:  (PRTOUT  FILE-NAME  IOT  [DIR  [WINDOW!)}) 

VALUE:  NIL 

EFFECT:  PRTOUT  takes  the  virtual  array  in  FILE-NAME  and  displays 
it  on  the  standard  output  file.  The  standard  output 
file  is  assumed  to  be  a 132  column  ASCII  printer.  The 
virtual  array  is  opened  (V AO)  with  the  WINDOW  parameters 


(MIN-X  MAX-X  MIN-Y  MAX-Y) 


If  the  virtual  array  window 
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is  wider  than  126  columns,  then  PRTOUT  prints  the  array 
out  in  vertical  strips,  so  that  the  whole  winoow  is 
reproauceo.  If  DIR  is  absent  or  NIL,  then  the  virtual 
array  is  printed  out  from  lower  row  numbers  to  higher 
row  numbers;  it  DIR  is  non-NIL,  then  the  array  is 
displayed  in  the  opposite  order.  Each  array  element  in 
the  window  is  modifiea  oy  the  function  (of  one  variable) 
IOT.  If  10T  is  NIL,  then  function  MANIFEST  is  usea 
instead.  PRTOUT  assumes  that  IOT  returns  a LISP  object 
that  reouires  only  a single  print  position  when  the 
object  is  passeo  to  PRINl. 

NOTES:  FILE-NAME  is  a string  node  defining  a valid  UNIX  file. 

IOT  must  be  cognizant  of  the  byte-size  ana  type 


(floating 

0 r 

integer. 

etc)  of 

data  in 

the  virtual  array. 

W I N DOW 

i s 

ae  f i ne d 

by  the 

A - 1 up  l e 

MIN-X  MAX-X  MIN-Y 

MAX -Y  . 

The 

default 

va lues  for 

missing  window 

specification  arguments  are  0,  X -p i c t u r e -d i me  ns i on , 0, 
y-picture-dimension,  respectively. 

EXAMPLE:  The  following  code  will  display  a "chain  code"  picture 
on  the  printer.  Assume  that  the  picture  is  namea 
"/cnain"  ana  that  each  of  its  picture  points  has  three 
fields.  The  first  fielo  (F)  is  1 when  the  point  is  part 
of  the  foreground  (curve  or  intersection)  and  0 when  the 
point  is  part  of  the  background.  The  second  field  (I) 
is  1 when  two  or  more  curves  have  crossed  the  point  ana 
0 when  at  most  one  curve  has  crossed  the  point.  The 
third  field  (C)  is  the  chain  coae  value  for  those  points 


3 .U. 1 7. 


CALLS: 


VALUE: 
EFFECT: 
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on  a curve  ana  0 tor  backyound  points.  The  C tiela  is 
the  least  significant  3 bits  of  a point.  The  I field  is 
the  next  most  significant  bit.  The  F field  is  the  next 
most  significant  bit  above  the  I field.  The  chain  code 
direction  and  print  symbols  are  defined  as  follows: 

701  ' background  points  are  "bH 


6 * 

2 

< > 

intersection  points  are 

5 4 

3 

/ v \ 

<c  set  q 

CIOT 

( l a mod  a 

<-v) 

<cond 

[ < z e r op 

(logand  20q 

- v)>  "b"] 

[ < z e r op 

( logana  1 Oq 

- v))>  "»"] 

[T  <ca  r 

(nth  ' ( ! **  • 

' *>  ? \ ! v •/  '<  »') 

( a ad  1 

(logand  7q  -v)))>3> 

)> 


< P K T 0 U T “/chain"  CI0T> 


SC ANOUT 

(SCANOUT  FILE-NAME  IOT  [DIR  [WINDOW]}) 

(SCANOUT  FILE-NAME-LIST  IOT  [DIR  [WINDOW]]) 

NIL 

SCANOUT  takes  the  virtual  array(s)  in  F I LE-NAME (-L I ST ) 
and  displays  them  on  the  scanner.  The  scanner  is 
assumed  to  oe  set  up  to  receive  a 256x256  picture.  All 
virtual  arrays  are  opened  (V AO)  with  the  same  WINDOW 
parameters  (MIN-X  MAX-x  MIN-Y  MAX-Y).  If  DIR  is  absent 


or  NIL.  then  the  array(s)  are  scanned  out  from  lower  row 
numoers  to  higher  row  numbers.  If  DIR  is  non-NILi  then 
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the  array(s)  are  displayed  in  the  opposite  order.  Each 
array  element  is  modified  by  the  function  (of  one 
variaole)  IOT.  If  IOT  is  NIL.  then  the  function 
MANIFEST  is  used  instead. 

NOTES:  FILE-NAME  is  a string  node  defining  a valid  UNIX  file. 

IOT  must  be  cognizant  of  the  byte-size  and  type  of  data 
in  the  virtual  array. 

WINDOW  is  defined  by  the  4-tuple  MIN-X  MAX-X  MIN-Y 
max-y.  Tne  default  values  tor  missing  window 
specification  arguments  are  0.  X-p i c t ur e -d i me  ns i on , 0, 

Y-picture-dimension,  respectively. 

EXAMPLE:  The  following  code  will  display  a picture  (with  less 
than  257  columns)  on  the  scanner.  The  picture  name  is 
"/pict".  Each  element  of  "/pict"  is  one  byte  long.  The 
grey  values  of  "/pict"  range  from  0 to  15.  The  IOT  in 
this  example  will  extend  the  range  of  grey  values  from  0 
to  255  (really  240). 

(csetq  IOT  (lambda  (-v)  ctimes  16  -v>)) 

(scanout  "/pict”  IOT) 


| 


eel: 


— — 
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4.  The  VECTOR  Package 

4.1.  Introduction 

While  POP  11  LISP  is  a powerful  programming  language,  our 
experience  writing  picture  processing  software  revealed  four 
areas  for  improvement  in  LISP,  The  improvements  eliminate  the 
inefficient  or  awkward  language  constructs  that  are  necessary  to 
perform  some  Basic  picture  processing  tasks.  This  section 
descrioes  the  LISP  functions  implemented  in  the  VECTOR  package  to 
alleviate  these  deficiencies.  The  VECTOR  package  software  is 
loaded  by  evaluating  the  expression  (load  "/Isp/vct")  after 
typing  X lisp  to  the  UNIX  SHELL  • The  following  paragraphs  will 
descrioe  features  of  the  VECTOR  package. 

4.1.1,  Extended  data  types 

Single  (or  multi)  dimensioned  arrays  are  not  standard  LISP 
data  structures*  However,  many  LISP  systems  implement  arrays  for 
user  convenience.  POP  11  LISP  supports  pointer,  logical  (T  or 
NIL),  signed  and  unsigned  Byte,  integer  word , f loat ing  point,  ana 
double  precision  floating  point  single  dimensional  arrays.  The 
picture  processing  software  accommodates  more  oata  types,  such  as 
signed  ana  unsigned  binary  data,  double  precision  integer  data, 
and  single  and  double  precision  complex  numbers.  Simulating 
these  data  types  with  POP  11  LISP  arrays  proved  to  be  quite 
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awkwara.  Also  the  arithmetic  functions  that  handled  these 
simulated  data  types  were  complicated  ana  inefficient.  This  data 
type  problem  was  eliminated  by  programming  a new  function  named 
VECTOR  to  create  singly  dimensioned  arrays  for  all  the  data  types 
used  by  "Mni-xAP  and  Virtual  Arrays.  A set  of  arithmetic 
functions  extenoing  several  basic  arithmetic  operations  to  these 
new  data  types  were  also  constructed. 

4.1.2.  Iteration 

Although  it  can  be  argued  that  iteration  is  inherently 
non- L I S P- l i k e or  less  elegant  than  recursion,  picture  processing 
routines  commonly  apply  the  same  operation  iteratively  to 
suo-regions  of  pictures.  Consequently.  effective  picture 
processing  requires  efficient  methods  of  iteration.  Iteration  is 
often  performed  Dy  manipulating  indices,  as  in  FORTRAN  DO  loops. 
The  function  MAPN,  in  file  /Isp/mapn,  will  call  a given  function 
once  for  each  integer  in  a range. 

4.1.3.  Node  allocation 

LISP's  method  of  evaluation  creates  many  data  nodes  that  are 
used  for  a short  period  of  time  ana  then  discarded.  For  example, 
a new  data  node  must  be  allocated  for  every  reference  to  an 
element  of  a LISP  array  (except  pointer  arrays,  byte  arrays,  and 
word  arrays  when  the  value  is  p r e- a 1 1 o c a t ed ) • Every  LISP 
function  that  returns  a numDer  as  a result,  also  must  allocate  a 
new  data  node  to  hold  that  result.  Whenever  the  result  of  a 
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calculation  is  returned  to  an  element  of  an  array  and  no 
intermediate  results  were  CSETQed  or  SETQed.  then  all  those  node 
generations  represent  wasted  effort.  This  waste  manifests  itself 
in  two  ways.  One  way  is  the  time  it  took  to  allocate  the  node 
that  will  be  discarded.  The  other  way  is  by  reducing  the  amount 
of  available  storage,  and  thus  hastening  the  execution  of  a time 
consuming  garoage  collection  process  to  retrieve  all  the 
discard eo  nodes . 

The  VECTOR  package  allays  the  node  allocation  problem  oy 
three  separate  measures.  First,  a few  VECTOR  package  functions 
return  NIL  instead  of  a numDer  as  their  result.  The  second 
measure  the  VECTOR  package  takes  to  reduce  the  node  allocation 
problem  is  to  define  new  argument  protocols  so  that  VECTOR 
package  functions  can  get  argument  values  directly  without  the 
overhead  of  an  intermediate  node  generation  to  contain  the 
argument  value.  For  example.  the  LISP  syntax  for  adding  two 
elements  of  a vector  together  is  (PLUS  (V  I)  (V  J))),  where  V is 
a vector  and  I and  J are  numbers.  But  the  evaluation  of  (V  I) 
ano  (V  J)  causes  the  value  nodes  to  be  generated  before  the 
function  PLUS  can  be  called.  ADD  is  the  VECTOR  package 
"equivalent"  to  PLUS.  The  expression  (ADD  (V  I)  (V  J))  would 
also  generate  two  value  nodes  before  function  ADD  is  called.  But 
the  expression  (ADD  V I V J)  will  return  the  same  value  without 
the  overhead  of  the  two  node  generations.  Note  also  that  the 
second  ADD  expression  requires  two  fewer  implicit  calls  to  EVAL. 

The  third  measure  used  oy  the  VECTOR  package  to  reduce  node 
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allocation  is  to  allow  the  results  of  a VECTOR  package  function 
to  Be  stored  directly  in  an  element  of  a vector.  for  example, 
the  expression  (V  I (INC  V I))  increments  the  value  of  the  Ith 
element  of  vector  v and  returns  the  new  value  of  the  Ith  element. 
The  evaluation  of  (INC  V I)  causes  the  generation  of  a data  node 
tor  the  result  of  incrementing  the  value  in  the  Ith  element  of  V. 
This  data  node  is  returned  as  the  value  of  the  entire  expression. 
The  function  VSET  allows  a VECTOR  package  function  to  be  called 
without  the  generation  of  a data  node  for  the  result.  The 
expression  (VSET  V I INC  V I)  increments  the  Ith  element  of  V 
without  an  extra  node  generation.  However,  the  returned  value  of 
tne  VSET  expression  is  V.  If  a result  is  being  stored  in  a 
vector  ana  the  result  value  is  not  needed,  then  the  use  of  the 
function  VSET  will  help  reouce  needless  node  allocation.  it  also 
executes  faster  than  the  nesteo  expression. 

4.1.4.  Minor  extentions 

The  set  of  LISP  arithmetic  functions  and  predicates  is 
incomplete.  For  example,  there  is  a less-than  predicate  (LESSP) 
Dut  no  l e s s- 1 han-or-eaua  l predicate  (defined  by  <lambda  (X  Y) 
<not  (greaterp  X Y)>>).  Only  the  predicates  for  zero,  minus, 
eaual,  greater-than,  and  less-than  are  defined  in  POP  11  LISP. 
Several  useful  arithmetic  functions  are  undefined,  e.g.»  absolute 
value  or  minimum  (of  a set  of  numbers).  The  VECTOR  package 
implements  a complete  set  of  predicates  ( EQL  * NEQ,  6T , GE,  LT , 
LE,  E 3 U , NEU,  GTl),  GEO,  LTO,  LEO)  defined  over  both  the  standard 
LISP  data  types  ana  the  extended  VECTOR  package  data  types.  The 
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following  arithmetic  functions  are  also  implementeo  by  the  VECTOR 
package:  ADO,  SUB,  MULT,  DIV,  MIN,  MAX,  INC,  DEC,  ABS,  NEGATIVE. 
The  following  conversion  functions  are  implemented:  INT,  REAL, 
IMAGINARY,  COMPLEX.  Some  integer  and  logical  operations  are  also 
implemented. 


4.2.  VECTOR  Package  Functions 


4.2.1.  Convent i ons 


Some  of  the  variables,  appearing  in  the  cocument at i on  of 
this  appendix,  have  special  meanings: 

FCT  aenotes  a LISP  function,  system  or  user  aefined 

( i n t e rp r e t i ve  Lambda,  or  compiled). 

VFCT  denotes  a function  of  the  VECTOR  package. 

I denotes  an  index  used  to  reference  an  element  of  a 

vector.  I is  implicitly  a number  (node). 

V denotes  a vector  function,  that  is,  the  name  of  a 

single  dimensional  array  created  oy  the  function 
VECTOR. 

A,B  or  A1  ...  An  denote  arguments  to  VECTOR  package 
functions.  VECTOR  package  arguments  are  defined 
differently  than  ordinary  LISP  arguments.  A 
VECTOR  package  argument  is  identical  to  a LISP 
argument  if  the  argument  is  not  a linker  node. 
However,  a VECTOR  package  argument  can  require 
two  LISP  arguments.  This  occurs  when  the  first 
LISP  argument  is  a vector,  V (created  by  VECTOR) 
and  the  second  LISP  argument  is  a number  node, 
I.  VECTOR  package  functions  treat  this  pair  of 
arauments  as  a request  for  the  value  of  the  Ith 
element  of  the  vector  V. 


Image  Processing  Software  under  UNIX 


PAGE  4-6 


• 2 • 2 * 

4 . 2 « £ ■ 1 
C ALL 
VALUE 

EFFECT 

NOTES 


Vector  functions 

VECTOR 

(vector  SIZE  TYPE) 

A one  dimensional  vector  (a  special  kind  of  function)  of 
length  S I Z E ♦ 1 and  of  type  TYPE* 

Space  for  the  vector  is  allocated  by  the  same  method  the 
LISP  function  ARRAY  uses. 

Vector  elements  are  numberea  from  zero  to  SIZE.  If  SIZE 
is  negative,  the  value  zero  is  suostitutea  for  SIZE. 
The  legal  types  (and  the  corresponding  values  of  TYPE) 
of  vectors  are: 

U Signed  bit  (0  or  -1) 

1 Unsigned  bit  (0  or  1) 

2 Signed  byte  (-128  to  127) 

3 Unsigned  byte  (0  to  255) 

4 Signed  word 

5 Signed  word 

6 Signed  double  word  (integer) 

7 Floating  point 

8 Double  precision  floating  point 

10  Double  precision  complex 

If  TYPE  is  not  between  0 and  10,  the  value  5 is 
substituted  for  TYPE. 

Vectors  are  functions;  the  rules  for  the  evaluation  of 
vectors  are  as  follows.  Assume  that  V and  U are  vectors 
(SETQed  from  (VECTOR  SIZE  TYPE)).  Let  I and  J be  numbers 


w 
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such  that  -1  < I < (ADD1  (VECTORL  V>>  and  -1  < J < 
(ADDl  (VECTORL  U)).  Let  ft  represent  a number  and  S 
represent  a string.  Then: 


(V)  evaluates  to  V and  (U)  evaluates  to  U. 


(V  I)  evaluates  to  the  contents  of  the  Itn 

element  of  V.  This  value  is  returned  as  an 
integer  node  ft » if  its  value  is  small 
enough,  or  as  a string  (node)  S containing 
the  type  of  *he  value  as  well  as  the  value 
itself. 


(V  I ft ) evaluates  to  ft  and  replaces  the  Ith 

elemtnent  of  V with  V's  representation  tor 
the  value  ft  • 


(V  I S)  evaluates  to  S and  replaces  the  Ith  element 

of  V with  V's  re p re  sen t a t i on  tor  the  value 
in  S . 

(V  I (U  J))  is  a special  case  of  (V  I tt ) 
or  (V  I S)  because  (U  J)  evaluates  to  a 
number  tt  or  a string  S. 

(V  I U J)  evaluates  to  NIL.  The  Ith 
element  of  V is  replaced  by  the  value  of  the 
Jth  element  of  U. 


when  an  element  of  a vector  is  being  set  to  some  value, 
that  value  is  converted  to  the  rep r e se nt a t i on  that 
corresponds  to  the  type  of  the  vector.  Thus,  if  V is  a 
floating  point  vector,  then  (V  1 0)  would  store  a 
floating  point  zero  in  the  first  element  of  V. 

4. 2. 2. 2.  VECTORP 


CALL:  (vectorp  v) 


VALUE:  The  type,  an  integer  between  0 and  10,  of  the  vector 
or  NIL  if  V is  not  a vector. 

4. 2. 2. 3.  VECTORL 

CALL:  (vectorl  V) 

VALUE:  The  number  of  the  highest  element  of  vector  V or  NIL 
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V is  not  a vector 

NOTES:  (VECTORL  V)  returns  1 fewer  than  the  number  of  elements 
in  V because  vectors  have  a tero  element. 

4.2.2.4.  CLEARV 


CALL:  (clearv  V) 

value:  nil 

EFFECT:  The  vector  v is  cleared  to  tero. 

NOTES:  V must  be  a VECTOR*  not  an  Array. 

4.2.C.5.  VSET 

call:  (vset  V I VFCT  Al  ...  An) 

VALUE:  The  vector  V. 

EFFECT:  The  result  of  applying  the  VECTOR  package  function  VFCT 
to  the  arguments  Al  ...  AN  is  stored  in  the  Ith  element 
of  vector  V. 

NOTES:  The  above  call  is  equivalent  to 

(OR  (V  I (VFCT  Al  ...  An))  V)  but  VSET  generates  no 
needless  data  node  for  the  result  of  VFCT. 


V must  be  a vector 
I must  oe  integer  valued 

VFCT  must  be  one  of  the  following  functions: 
ADD,  SUP,  MULT,  DIV,  MOD,  MIN,  MAX 
IADD,  I S U8  » LAND,  LEOV,  LOR,  LXOR, 

ABS,  DEC,  INC,  NEGATIVE, 

INT,  REAL,  IMAGINARY,  COMPLEX. 


4.2.3.  iteration  function 


4. 2. 3.1.  MAPN 

CALL:  (mapn  BEGIN  END  FCT) 

VALUE:  NIL 

EFFECT:  The  function  of  one  variable  FCT  is  called 


first  with 


-~k: 


A 
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NOTES  : 


4 . £ . 4 • 

4. 2. 4.1  . 
CALL: 
VALUE  : 

NOTES  : 
4. 2. 4.2. 

C ALL  : 
VALUE  : 


value  BEGIN*  then  once  for  each  integer  value  oetveen 
BEGIN  and  END*  and  finally  with  value  END.  IE  BEGIN  ana 
END  are  the  same  number,  then  ECT  is  called  just  once. 

If  ECT  is  not  a function,  then  LISP  will  request  the 
user  to  supply  a function. 

BEGIN  and  END  should  be  integer  valued;  MAPN  does  not 
check. 

If  BEGIN  is  less  then  END,  then  MAPN  increments  the 
index  value  passed  to  ECT,  otherwise  MAPN  decrements  it. 

Before  a function  that  uses  MAPN  is  compiled,  the  file 
"/lsp/fixM  should  be  loaded.  This  allows  the  LISP 
compiler  to  compile  MAPN  calls  of  internal  lambda 
functions  without  declaring  the  free  variables  to  be 
fluid. 

MAPN  can  be  loaded  from  the  file  "/Isp/mapn". 

Predicates 

GT 

(gt  A 9 ) 

T,  it  argument  A's  numeric  value  is  greater  than 
a rg  ume  n t B ' s . 

NIL,  otherwise. 

Similar  to  LISP  predicate  GREATERP 
GE 

(ge  A B) 

T,  if  argument  A's  numeric  value  is  greater  than  or 
equal  to  argument  B's. 


Image  Processing  Software  under  UNIX 


PAGE  4-10 


NOTES : 

4. £.4.3. 
CALL: 
VALUE: 


L 


NOTES : 

4.C.4.4. 
C ALL  : 
V AlUE  : 


NOTES  ; 

4. £.4.3. 

call: 
VALUE  : 


NOTES  : 
4. ^.4.6. 
CALL  : 
VALUE: 


NOTES 


NIL*  otherwise. 

Similar  to  (OR  (GREATERP  A B)  (EQUAL  A B)) 


EQL 


(eo l A B) 

T,  it  argument  A has  the  same  numeric  value  as 
3 . 


NIL,  otherwise. 

Similar  to  LISP  Dreoicate  EQUAL  applied  to 
arguments. 


NE 


( ne  A B ) 

T,  if  argument  A's  numeric  value  is  not 
a r g ume  n t B ' s . 

NIL,  otherwise. 

Equivalent  to  (NOT  (EQL  A B)) 

LE 

( le  A B ) 

T , i t argument  A's  numeric  value  is  less  than  or 
a r g ume  n t B ' s . 

NIL*  otherwise. 

Equivalent  to  (GE  B A) 

LT 

(It  A B) 

T,  it  argument  A's  numeric  value  is  less  than 
B's  . 

ML,  otherwise. 

Similar  to  LISP  predicate  LESSP 


a rgument 


numeric 


equal  to 


equal  to 


argument 
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Equivalent  to  (GT  B A) 

4. 2.4.7.  GT(j 
CALL:  (gtO  A) 

VALUE:  T,  if  argument  A's  numeric  value  is  positive. 

NIL.  otherwise 

NOTES:  Equivalent  to  (GT  A 0) 

4. 2. 4. 8.  GEO 
CALL:  CgeO  A) 

VALUE:  T,  it  argument  A is  non- negative. 

NIL.  otherwise 

NOTES:  Equivalent  to  (GE  A 0) 

4. 2. *..9.  EQO 

CALL:  (eqO  A) 

VALUE:  T,  it  argument  A has  value  zero 
NIL.  otherwise 

NOTES:  Similar  to  LISP  predicate  ZEROP. 

4.2.4.10.  NEU 
CALL:  (neO  A) 

VALUE:  T,  it  argument  A's  numeric  value  is  non-zero. 

NIL.  otherwise 

NOTES:  Equivalent  to  (NE  A 0) 

4.2.4.11.  LEO 
CALL:  < leO  A) 

VALUE:  T,  it  argument  A's  numeric  value  is  negative  or  zero 
NIL,  otherwise. 


NOTES:  Equivalent  to  (LE  A 0) 


4.2. -.12 

CALL: 
VALUE  : 

NOTES: 

4.2.5. 

4. 2. 5.1 . 

CALL: 

VALUE : 

NOTES  : 

4. 2. 5. 2. 

CALLS: 

VALUE : 

NOTES : 
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LTO 

(ItU  A) 

T,  it  argument  A's  numeric  value  is  negative. 

NIL.  otherwise. 

Similar  to  LISP  predicate  MINUSP 
Equivalent  to  (LT  A 0)  top 

loating  point  arithmetic  functions 

ADO 

(ado  A 1 ...  An) 

(add  A)  returns  the  value  of  A 
(aod)  returns  an  integer  zero 
The  double  precision  floating  point  sum  of  the  arguments 
A 1 ...  An.  The  imaginary  parts  of  complex  arguments  are 

ignored . 

ADD  never  returns  a complex  result. 

ADD  accesses  only  the  real  parts  of  complex  valued 

a r g ume  n t s . 

SUB 

( sup  A 1 A2  ...  An) 

(suo  A)  returns  the  value  of  A 
(sub)  returns  an  integer  zero 
The  aouDle  precision  floating  point  aifference  of  the 
value  of  A1  and  the  sum  of  the  argument  values 
A2  ...  An. 

SUB  accesses  only  the  real  parts  of  complex  valued 


argument s 
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2. 5.3  . MULT 


CALLS:  (mult  A1  ...  An) 


(mult  A)  returns  the  value  of  A. 


(mult)  returns  an  integer  zero. 


VALUE:  The  douole  precision  floating  point  product  of  the 


argument  values  A1  ...  An. 


NOTES:  MULT  accesses  only  the  real  parts  of  complex  valueo 


arguments. 


£.5.4. 


CAlLS:  (div  A1  Ac  ...  An) 


(div  A)  returns  the  value  of  A. 


(div)  returns  an  integer  zero. 


VALUE:  The  douole  precision  floating  point  quotient  of  the 


value  of  argument  A1  divideo  by  the  product  of  the 


argument  values  A2  ...  An. 


NOTES:  DIV  accesses  only  the  real  parts  of  complex  valueo 


a rgument  s • 


2.5.5. 


CALLS:  (min  A1  ...  An) 


(min  A)  returns  the  value  of  A. 


(min)  returns  an  integer  zero. 


VALUE:  The  douple  precision  floating  point  minimum  of  the 


arguments  values  A1  ...  An. 


NOTES:  min  accesses  only  the  real  parts  of  complex  valued 


argument  s . 


2.5.6. 


CALLS:  (max  A1  ...  An) 


* 
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(max  A)  returns  the  value  of  A. 

(max)  returns  an  integer  zero. 

VALUE:  The  aouDle  precision  floating  point  maximum  of  the 
argument  values  A1  ...  An. 

NOTES:  max  accesses  only  the  real  parts  of  complex  valued 
a r g ume  n t s . 

4.1.0.  Integer  arithmetic  and  logical  functions 


4.?. 6.1  . I A 0 D 


CALLS  : 


VALUE  : 
NOTES  : 


4.2.6  • 2 « 


(iaod  A 1 ...  An) 

(iado)  returns  an  integer  zero. 

Tne  integer  sum  of  argument  values  A1  ...  An. 
A 1 ...  AN  must  all  be  integer  valued. 

ISUB 


CALLS:  (isub  A1  A?  ...  An) 

(isub  A)  returns  the  value  of  A. 

(isub)  returns  an  integer  zero. 

VALUE:  The  integer  difference  of  the  value  of  Al  and  the  sum  of 
the  argument  values  A2  ...  An. 

NOTES:  Al  ...  AN  must  all  oe  integer  valued. 

4.2. 0.3.  LAND 


CALLS:  (land  Al  ...  An) 

(land  A)  returns  the  value  of  A. 

(lano)  returns  an  integer  zero* 

VALUE:  The  logical  AND  of  the  argument  values  Al  ...  An. 
NOTES:  Al  ...  AN  must  all  be  integer  valueo. 


4 • Z « 6 • 4 • 
CALLS: 

VALUE : 

NOTES  : 

4. 2. 6. 5. 
CALLS: 

VALUE : 
NOTES  : 

4.2. 6.6. 

CALLS  : 

VALUE  : 

A • 2 • 6 • 7 . 
CALL  : 
VALUE  : 

NOTES  : 
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LEQV 

(leqv  A 1 . . . An) 

(leqv  A)  returns  the  value  of  A. 

(leqv)  returns  an  integer  zero. 

The  logical  EQUIVALENCE  of  the  argument  values 
A 1 ...  An# 

A 1 ...  AN  must  all  oe  integer  valued. 

LOR 

(lor  A 1 ...  An) 

(lor  A)  returns  the  value  of  A. 

(lor)  returns  an  integer  zero. 

The  logical  OR  of  the  argument  values  A1  ...  An. 

A 1 ...  AN  must  all  oe  integer  valueo. 

LX  OR 

Uxor  A 1 ...  An) 

Uxor  A)  returns  the  value  A. 

Uxor)  returns  an  integer  zero. 

The  logical  EXCLUSIVE-OR  of  the  argument  values 
A 1 ...  An. 

ASHIFT 

(ashift  N A) 

The  (integer)  value  of  argument  A arithmetically  shifted 
N places  to  the  left. 

N and  A are  automatically  converted  to  double  precision 
integers.  When  N is  negative  ASHIFT  shifts  A 
arithmetically  to  the  right. 

-33  < N < 32. 


■HM 1 
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*♦•2.6  « b . 


C ALL  : 
VALUE  : 


NOTES  : 


4.2. O.V. 


C ALL  : 
VALUE  : 


NOTES  : 


*••2. 6*10 


CALL  : 
VALUE  : 


NOTES: 


LSHIFT 

((.shift  N A) 

The  (integer)  value  of  argument  A logically  shifted  h 

places  to  the  left. 

N and  A are  automatically  converted  to  double  precision 
integers.  When  N is  neqative  LSHIFT  shifts  A logically 
to  the  right. 

-34  < N < 32. 

FLD 

(f la  S B I T LNG  A) 

The  LNG  bits  beginning  witn  bit  number  SBIT  of  the 
(aouble  precision  integer)  value  of  Argument  A.  The 
result  is  right  justified. 

SBIT  ana  LnG  are  automatically  converted  to  single 

precision  integers.  A is  a ut oma t i c a l l y converted  to  a 
douole  precision  integer. 

-1  < SBIT  < 33. 

0 < LNG  < 33. 

G < SBIT*LNG  < 33. 

OFLO 

(of  Id  SBIT  LNG  A B) 

The  integer  value  of  argument  A modified  by  replacing 
the  LNG  bits  starting  at  bit  SBIT  of  A with  the 
right-most  LNG  Dits  of  the  integer  value  of  argument  B. 
SBIT  and  LNG  are  automatically  converted  to  single 

precision  integers. 

A ano  B are  a t uoma t i c a l ly  converted  to  double  precision 


I 


4 • 2 • 7 • 

4.2. 7.1 
CALL 
VALUE 
NOTES 


4 .2.7.2 
CALL 

VALUE 

NOTES 

4.2. 7.3 
CALL 

VALUE 

NOTES 
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integers. 

-1  < S 0 1 T < 33. 

0 < LNG  < 33. 

0 < SBIT-fLNG  < 33. 

Unary  arithmetic  functions 

ABS 

( ab s A ) 

The  absolute  value  of  the  argument  A. 

The  value  returned  has  the  same  type  as  the  input 
argument  A (unless  A is  complex) 

ABS  does  not  return  the  correct  result  for  a complex 
argument  because  there  is  no  square  root  routine.  Tor  a 
complex  value  A + Bi  ABS  returns  A*A+B*B. 

INC 

( i n c A ) 

The  value  of  argument  A plus  1. 

The  value  returned  is  the  same  type  as  the  input 
argument  A.  For  a complex  value  A*Bi  INC  returns 
( A ♦ 1 ) ♦B  i . 

DEC 

: (dec  A ) 

The  value  of  argument  A minus  1. 

: The  value  returned  is  the  same  type  as  the  input 
argument  A.  For  a complex  value  A+Bi  DEC  returns 


( A- i > ♦B  i 
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4 .2 . 7.4  . NEG 
CALL:  (neg  A) 

VALUE:  The  value  0 minus  the  value  of  argument  A. 

NOTES:  The  value  returnee  is  the  same  type  as  the  input 
argument  A.  For  a complex  value  A+Bi  NEGATIVE  returns 

< -a ) ♦ < -a  > i . 

4.2.0.  Conversion  functions 

4. 2. 6.1 . INT 
CALLS:  (int  A) 

(int)  returns  an  integer  zero. 

VALUE:  The  truncated  integer  value  of  argument  A. 

If  A is  an  integer  value,  that  value  is  returned. 

It  A is  a floating  point  value.  the  nearest  integer 
value  between  A and  zero  is  returned. 

It  A is  a complex  value,  the  nearest  integer  value 

between  the  real  part  of  A and  zero  is  returned. 

4 .2.0. 2 . REAL 
CALLS:  (real  A) 

(real)  returns  a double  precision  floating  point  zero. 
VALUE:  The  double  precision  floating  point  value  of  argument  A. 

If  A is  an  integer,  its  floating  point  equivalent  is 
re  t u r ne  d • 

It  A is  a real  value,  that  value  is  returned. 

If  A is  a complex  value.  the  real  part  of  A is 


returned. 
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4.2.0 .3 
CALLS 

VALUE 


4. 2. 8. 4 
CALLS 

V Vb  U E 

*. . 

4 1 2 . 9 . 

4. 2. 9.1 
, CALL 
value 

NOTES 


IMAGINARY 
(imaginary  A) 

(imaginary)  returns  a double  precision  floating  zero. 
The  imaginary  part  of  the  argument  A. 

If  A is  a complex  value,  the  imaginary  part  of  A is 
ret  urneo  • 

If  A is  an  integer  or  real  value,  a floating  point  aero 
is  ret  urned . 

COMPLEX 
( c omp l ex  A B ) 

(complex  A)  returns  A+Oi 
(complex)  returns  Q + Oi 

The  double  precision  complex  value  (REAL  A)*(REAL  B)i 

Miscellaneous  functions 

UPTO 

(upto  L FCT) 

A list  of  the  non-NIL  values  that  result  from  applying 
FCT,  a function  of  one  argument,  to  successive  members 
of  the  list  l. 

If  FCT  is  not  a function,  then  LISP  will  request  the 
user  to  supply  a function. 

UPTO  is  similar  to  the  LISP  function  INTO,  but  UPTO 
filters  out  NILS. 

Before  a function  that  uses  UPTO  is  compiled,  the  file 
"/Isp/fix"  should  be  loaded.  This  allows  the  LISP 
compiler  to  compile  UPTO  calls  of  internal  lambda 


Image  Processing  Software  under  UNIX 


PAGE  4-20 


functions  without  declaring  the  free  variables  to  be 

fluid. 

UPTO  can  be  loaded  from  the  tile  "/Isp/upto". 

2.V.2.  CONCAT 
CALL:  (concat  SI  ...  Sn) 

VALUE:  The  string  that  is  the  concatenation  of  the  print  names 
of  SI  ...  Sn. 

NOTES:  Si  may  oe  any  LISP  object  that  EXPLODE  can  handle.  Si 
is  usually  a string,  an  atom,  or  a number. 

CONCAT  can  be  loaded  from  the  file  "/Isp/concat". 

2.V.3.  SORT 
CALL:  C sq  r t X ) 

VALUE:  The  doub l e -p r e c i s i on  square  root  of  X. 

FFcCT:  SORT  uses  Newton's  method  to  calculate  the  square  root 
of  x.  when  x is  negative,  SORT  generates  a "floating 
exception"  and  evaluates  an  (ERROR  -10). 

NOTES:  SORT  can  be  loaded  from  the  file  "/lsp/sqrt"  or 

"/ l isp/sqrt". 

2.V.4.  EXP 
CALL:  (exp  X) 

VALUE:  e **  X 

FFECT:  The  douole-precision  quantity  e**X  is  calculated  and 
returned. 

NOTES:  EXP  returns  0.0  when  X is  less  than  -88. 

EXP  takes  a "floating  exception"  when  X is  greater  than 

88. 

EXP  can  be  loaded  from  the  file  "/Isp/exp"  or 
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•*/L  isp/exp”. 

4.2.9. 5.  LOG 
CALL:  (log  X) 

VALUE:  The  douole-prec i sion  natural  (to  the  base  e)  logarithm 
of  X . 

NOTES:  LOG  can  be  loaaeo  from  the  file  " /Isp/log"  or 
" /lisp/log ” . 

4. 2. 9. 6.  L0G2 
CALL:  ( I cg2  X ) 

VALUE:  The  aouole-precision  logarithm  to  the  base  2 of  X. 

NOTES:  L0G2  can  oe  loaded  from  the  file  "/lsp/logM. 

4.2. 9.7.  COS 
CALL:  (cos  X) 

VALUE:  The  cosine  of  x. 

NOTES:  COS  can  be  loaded  from  the  file  "/lsp/si n”  or 

"/lisp/sin". 

4.2.9.  d.  SIN 
CALL:  (sin  X) 

VALUE:  The  sine  of  X. 

NOTES:  SIN  can  be  loaded  from  the  file  "/Isp/sin”  or 

•’/lisp/sin". 

4. 2. 9. 9.  ATAN 
CALL:  (atan  X) 

VALUE:  The  douole-precision  arctangent  of  X. 

NOTES:  The  range  of  ATAN  is  -PI/2  to  PI/2. 

ATAN  can  be  loaded  from  the  file  "/Isp/atan"  or 


"/lisp/atan 
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4.2.9.10.  A T A N 2 

CALL:  ( at  an2  X Y) 

VALUE:  Tne  douo t e -p r ec i s i on  arctangent  of  X/V. 

NOTES:  The  range  of  ATAN2  is  -PI  to  PI. 

AT AN2  can  be  loaded  from  the  file  H/lsp/atan 


"/ l i sp/atan" 
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